home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / mgr / sparcmgr / doc.zoo / doc / usrman / doc.6 < prev    next >
Encoding:
Text File  |  1989-01-24  |  11.5 KB  |  446 lines
  1. '\"                        Copyright (c) 1988 Bellcore
  2. '\"                            All Rights Reserved
  3. '\"       Permission is granted to copy or use this program, EXCEPT that it
  4. '\"       may not be sold for profit, the copyright notice must be reproduced
  5. '\"       on copies, and credit should be given to Bellcore where it is due.
  6. '\"       BELLCORE MAKES NO WARRANTY AND ACCEPTS NO LIABILITY FOR THIS PROGRAM.
  7. '\"
  8. '\"    $Header: doc.6,v 4.1 88/06/29 17:05:09 bianchi Exp $
  9. '\"    $Source: /tmp/mgrsrc/doc/usrman/RCS/doc.6,v $
  10. .Sh page Using the Library
  11. Clients using 
  12. .I
  13. The C Interface Library
  14. .R
  15. should specify:
  16. .DS
  17. .ft \*(Ff
  18. #include "term.h"
  19. .ft R
  20. .DE
  21. which also includes 
  22. .DS
  23. .ft \*(Ff
  24. <stdio.h>
  25. .ft R
  26. .DE
  27. if it has not already been included.
  28. Programs are compiled either with
  29. .DS
  30. .ft \*(Ff
  31. cc -o foo foo.c term.o -I$(lib)
  32. .ft R
  33. .DE
  34. where $(lib) is the \*M include directory
  35. or simply
  36. .DS
  37. .ft \*(Ff
  38. cc -o foo foo.c -lmgr
  39. .ft R
  40. .DE
  41. if the library is installed in a standard location.
  42. The file
  43. .I term.o
  44. contains the functions listed in the last section.
  45. Several compile time options are available to the client program using
  46. the library.
  47. Normally, the library setup routine,
  48. .Fr m_setup
  49.  attempts to open 
  50. .I /dev/tty
  51. to communicate with \*M.
  52. Client programs may define the C preprocessor symbols
  53. .SM
  54. .I M_DEVICEIN
  55. .LG
  56. or
  57. .SM
  58. .I M_DEVICEOUT
  59. .LG
  60. to override the selection of
  61. .I /dev/tty
  62. for input or output respectively.
  63. After each macro call,
  64. the flush flag
  65. .SM
  66. .I M_FLUSH
  67. .LG
  68. is tested to see if output should be flushed to \*M.
  69. If the C preprocessor symbol
  70. .SM
  71. .I M_NOFLUSH
  72. .LG
  73. is defined, before the client program includes
  74. .I term.h ,
  75. The flush flag is never tested, and it becomes the responsibility of the
  76. client program to insure output is flushed at the appropriate times.
  77. .LP
  78. Several external variables maintained by the library are accessible to
  79. client programs.
  80. The
  81. .I stdio
  82. .SM
  83. .I FILE
  84. .LG
  85. pointers
  86. .I m_termin
  87. and
  88. .I m_termout
  89. are used for directing output to, and receiving input from \*M.
  90. These file pointers are initialized in
  91. .Fr m_setup
  92. \&, and may be changed by client programs after
  93. .Fr m_setup
  94.  is called.
  95. The integer
  96. .I m_flags
  97. contains the current library mode settings, as returned by
  98. .Fr m_setup
  99. \&.
  100. The 
  101. .SM
  102. .I M_MODEOK
  103. .LG
  104. and
  105. .SM
  106. .I M_FLUSH
  107. .LG
  108. bits of 
  109. .I m_flags
  110. may also be changed at any time after 
  111. .Fr m_setup 
  112.  is called.
  113. The integer
  114. .I m_envcount
  115. contains the current window context depth, and is used by
  116. .Fr m_popall
  117. to pop the appropriate number of contexts.
  118. .I M_envcount
  119. should not be changed by client programs.
  120. Finally, the character
  121. .I m_menuchar
  122. defines the menu separator character used by
  123. .Fr menu_load
  124. \&.
  125. This character, set to '\e005' by the library package,
  126. can be changed to any character that will not appear as part of
  127. a menu item or action.
  128. .Sh page Glossary
  129. .IP "\fBabsolute coordinates\fP" 0.5i
  130. .br
  131. .I "Absolute coordinates"
  132. is a coordinate system used in
  133. .I windows
  134. measured in units of pixels.
  135. .IP "\fBactive window\fP" 0.5i
  136. .br
  137. The
  138. .I active
  139. window is the window logically in the front of the display, which is
  140. receiving keyboard and mouse input.
  141. .IP "\fBalternate window\fP" 0.5i
  142. .br
  143. An
  144. .I "alternate window"
  145. is an additional window created by a client program that shares the
  146. communication channel with the main window.
  147. .IP \fBbitmap\fP 0.5i
  148. .br
  149. A
  150. .I bitmap
  151. is a rectangular array of bits, or pixels if the bitmap is
  152. currently on the display.
  153. .IP \fBchannel\fP 0.5i
  154. .br
  155. The
  156. .I channel
  157. is the bidirectional byte stream connecting \*M with
  158. the client program.
  159. The 
  160. .I channel
  161. is usually the program's standard input and output.
  162. .IP "\fBcharacter coordinates\fP" 0.5i
  163. .br
  164. .I "Character coordinates"
  165. is the 
  166. coordinate system used in windows for counting characters in
  167. .I columns
  168. and
  169. .I rows .
  170. .IP "\fBcharacter cursor\fP" 0.5i
  171. .br
  172. The
  173. .I "character cursor"
  174. is the location in the window where the next character will be placed.
  175. The cursor location is always highlighted on the active window.
  176. .IP "\fBchild menu\fP" 0.5i
  177. .br
  178. A
  179. .I "child menu"
  180. is the
  181. menu that will pop up when the user slides off to the right
  182. of a popped up 
  183. .I "parent menu" .
  184. .IP "\fBclient program\fP" 0.5i
  185. .br
  186. A
  187. .I "client program"
  188. is any Unix command that is running in an \*M window.
  189. Client programs may be existing programs, as might be found in
  190. .I /bin
  191. or new applications written specifically to take advantage of the
  192. windowing environment.
  193. .IP \fBclient-host\fP 0.5i
  194. .br
  195. The
  196. .I "client-host"
  197. is the computer that the client program is running on.
  198. It is often the same as the
  199. .I \*M-host
  200. machine, but it does not need to be.
  201. .IP "\fBdisplay coordinates\fP" 0.5i
  202. .I "Display coordinates"
  203. is a coordinate system used to measure pixels on the display.
  204. The top left corner of the display is at (0,0), with
  205. .I x
  206. increasing to the right, and
  207. .I y
  208. increasing down.
  209. .br
  210. .IP \fBexposed\fP 0.5i
  211. .br
  212. A window is
  213. .I exposed
  214. if it is entirely visible.
  215. .IP "\fBgraphics point\fP" 0.5i
  216. .br
  217. The
  218. .I "graphics point"
  219. is a location on the window, measured in the prevailing window
  220. coordinate system, that may serve as a reference location 
  221. or origin for many of the graphics operations.
  222. .IP \fBlistener\fP 0.5i
  223. .br
  224. A 
  225. .I listener
  226. is a window that has turned on the
  227. .SM
  228. .Fi ACCEPT
  229. .LG
  230. event and is willing to receive messages from other client programs.
  231. .IP "\fBmain window\fP" 0.5i
  232. .br
  233. A client program's
  234. .I "main window"
  235. is the window the program was started in.
  236. The client program may create and destroy alternate windows,
  237. but not its
  238. .I "main window" .
  239. If the user destroys a client program's
  240. .I " main window" ,
  241. the connection
  242. to \*M is severed, and the client program receives a
  243. .I hangup
  244. signal.
  245. .IP \fB\*M-host\fP 0.5i
  246. .br
  247. The
  248. \*M-host is the computer that \*M is running on. 
  249. .IP "\fBmouse cursor\fP" 0.5i
  250. .br
  251. The
  252. .I "mouse cursor"
  253. is a small bitmap or
  254. .I icon
  255. that tracks the movement of the mouse on the display.
  256. Normally the
  257. .I "mouse cursor"
  258. is a small arrow pointing north west.
  259. .IP \fBobscured\fP 0.5i
  260. .br
  261. A window is
  262. .I obscured
  263. when it is partially or totally covered by another
  264. window.
  265. .IP "\fBparent menu\fP" 0.5i
  266. .br
  267. A  menu is called a
  268. .I "parent menu"
  269. when sliding off to the right of a selected item causes
  270. another menu or
  271. .I "child menu"
  272. to pop up.
  273. .IP "\fBrelative coordinates\fP" 0.5i
  274. .br
  275. .I "Relative coordinates"
  276. is a coordinate system for windows where a single unit represents one
  277. thousandth of the way across (or down) the window.
  278. .IP "\fBscratchpad bitmap\fP" 0.5i
  279. .br
  280. A 
  281. .I "scratchpad bitmap"
  282. is a chunk of memory, allocated by \*M for use by a client program,
  283. that may hold a bitmap image that is not on the display.
  284. .IP "\fBsnarf buffer\fP" 0.5i
  285. .br
  286. The
  287. .I "snarf buffer"
  288. is a buffer maintained by \*M of arbitrary size that is accessible by all
  289. client programs.
  290. .IP "\fBtarget window\fP" 0.5i
  291. .br
  292. A
  293. .I "target window"
  294. is a window that is to receive a message from another window.
  295. .IP "\fBtext region\fP" 0.5i
  296. .br
  297. A 
  298. .I "text region"
  299. is the part of the window in which character text and the 
  300. functions that operate on characters work.
  301. The
  302. .I "text region"
  303. may be the entire window (the default)
  304. or a rectangular subregion within the window.
  305. .IP "\fBwindow border\fP" 0.5i
  306. .br
  307. The
  308. .I "window border"
  309. is a thin black border around every window that separates the
  310. window from the rest of the display.
  311. .IP "\fBwindow context\fP" 0.5i
  312. .br
  313. A
  314. .I "window context"
  315. contains the values for one or more aspects of the window's
  316. state.
  317. .I "Window context"
  318. a may be saved on a stack, and then restored at some later time.
  319. .IP "\fBwindow id\fP" 0.5i
  320. .br
  321. A
  322. .I "window id"
  323. is a unique number assigned to every window that may be used
  324. as an identifier when sending a message to the window.
  325. .I "Window id" s
  326. have two parts,
  327. the first part is the process number of the client program that
  328. was started when the window was created,
  329. the second part is the windows
  330. .I alternate
  331. window number, or
  332. zero for a main window.
  333. .Sh page Sample Client Program
  334. .LP
  335. This program, called
  336. .I close ,
  337. closes, or iconifies a window.  
  338. Its not a terribly useful application in its own right, but it does
  339. exercise several of the library calls.
  340. When 
  341. .I close
  342. starts up, it makes the window smaller,
  343. moves it toward the top of the display,
  344. then writes the word "closed" in it.
  345. If the window is covered by another window,
  346. it changes the word "closed" to "hidden", then flashes its window every
  347. 15 seconds as long as the window is covered.
  348. If the window is then uncovered, the word "hidden" gets changed back
  349. to "closed".
  350. Activating the window causes
  351. .I close
  352. to restore the window's original shape and contents, then exit.
  353. .LP
  354. .SS
  355. /* iconify a MGR window */
  356.  
  357. #include <signal.h>
  358. #include "term.h"
  359.  
  360. #define TIME    15                /* time interval for reminder */
  361. #define CONTEXT P_POSITION | P_WINDOW | P_FLAGS | P_EVENT | P_CURSOR
  362.  
  363. static char line[80];             /* event input buffer */
  364.  
  365. main()
  366.     {
  367.     int clean(), timer();         /* interrupt routines */
  368.     int x,y;                      /* window position on display */
  369.     char *msg = "closed";         /* closed window "icon" */
  370.  
  371.     /* setup the window environment */
  372.  
  373.     m_setup(M_FLUSH);             /* setup i/o, turn on flushing */
  374.     m_push(CONTEXT);              /* save current window context */
  375.     m_setmode(M_NOWRAP);          /* don't auto-wrap at right margin */
  376.     m_ttyset();                   /* set up tty modes */
  377.  
  378.     /* catch the appropriate signals */
  379.  
  380.     signal(SIGTERM,clean);        /* in case we get terminated */
  381.     signal(SIGALRM,timer);        /* for the reminder service */
  382.  
  383.     /* iconify the window */
  384.  
  385.     get_size(&x,&y,0,0);          /* fetch window coordinates */
  386.     m_sizeall(x,10,strlen(msg),1);/* move and resize window */
  387.     m_clear();                    /* clear the window */
  388.     m_printstr(msg);              /* print message in the window */
  389.  
  390.     /* catch events */
  391.  
  392.     m_setevent(ACTIVATE, "A\er"); /* window is now the active window */
  393.     m_setevent(COVERED,  "C\er"); /* covered by another window */
  394.     m_setevent(UNCOVERED,"U\er"); /* completely visible */
  395.     m_setevent(REDRAW,   "R\er"); /* redraw requested */
  396.  
  397.     m_clearmode(M_ACTIVATE);      /* bury the window */
  398.  
  399.     /* wait for an event */
  400.  
  401.     while(m_gets(line) != NULL)   /* read a line from MGR */
  402.         switch (*line) {
  403.         case 'A':                 /* window is activated */
  404.             clean();              /* clean up and exit */
  405.             break;
  406.         case 'C':                 /* window is covered */
  407.             m_clear();
  408.             m_printstr("hidden");
  409.             alarm(TIME);          /* turn on reminder */
  410.             break;
  411.         case 'R':                 /* system 'redraw' */
  412.         case 'U':                 /* window is uncovered */
  413.             m_clear();
  414.             m_printstr(msg);
  415.             alarm(0);             /* turn off reminder */
  416.             break;
  417.         case 'T':                 /* send reminder */
  418.             m_setmode(M_WOB);     /* highlight window */
  419.             m_bell();             /* ring the bell */
  420.             sleep(1);
  421.             alarm(TIME);          /* reset reminder timer */
  422.             m_clearmode(M_WOB);   /* reset window highlighting */
  423.             break;
  424.         }
  425.     }
  426.  
  427. clean()                           /* clean up and exit */
  428.     {
  429.     m_ttyreset();                 /* reset tty modes */
  430.     m_popall();                   /* restore window context */
  431.     exit(0);
  432.     }
  433.  
  434. timer()                           /* called at reminder timeout */
  435.     {
  436.     m_sendme("T\er");             /* send timeout message */
  437.     }
  438. .SE
  439. .Sh page Macros and Functions by Category
  440. .LP
  441. .FS *
  442. The routines marked with a dagger (\(dg) are functions,
  443. the other routines are macros.  The page number on which the macro or
  444. function is defined is printed in bold face after the name.
  445. .FE
  446.